SPRY Telnet Help Contents

The following Help Topics are available:

What is SPRY Telnet?

Starting SPRY Telnet

Editing Telnet Hosts

Opening Other Telnet Sessions

Printing in Telnet

Copying and pasting text in Telnet

Capturing text in a Telnet session

Using Scripts in Telnet

Customizing Telnet Settings

Custom Sessions in Telnet

Keyboard Remapping

Exiting Telnet

Telnet Menu Commands

Telnet Dynamic Data Exchange (DDE)

For Help using Help, press [F1].  Help revised April, 95.


What is SPRY Telnet?

SPRY Telnet™ allows you to connect to a remote host and execute programs as if you were directly working on that host, using an easy-to-use, customizable Windows interface.

SPRY Telnet's advanced terminal emulation services include printing and capturing of session activity, login scripts, custom configurable sessions, and support for multiple sessions.


Starting a Telnet Session

You can start SPRY Telnet  by clicking on the SPRY Telnet icon.  You will see the Open Telnet Session dialog.

You are prompted to type in either a Host Name, Session Name, or IP Address, or select a Host or Session from the lists.  You can also specify a telnet port, if necessary.

Once you have selected a host, custom session, or IP address, click OK.  SPRY Telnet will attempt to open a Telnet session to the specified host.


Open Telnet Session

You can connect to a host from the <Open Telnet Session> dialog by typing any of the following items:

Host Name

A name from your hosts file, or Telnet hosts list.

Session Name

A custom Telnet session you've created.

IP Address

The IP Address or fully qualified domain name of a host.

Hosts and Sessions can also be chosen from the displayed lists.

A Telnet Port can also be specified.

If you want to have Telnet remember the host or IP address you connected to, check Remember New Hosts.

Once you have selected a host, session, or IP address, click OK.  SPRY Telnet will attempt to open a Telnet session to the specified host.  If a connection is made, a Telnet Console with the name of that host, custom session, or IP address will be opened, and the host's 'login' prompt will be displayed.


Telnet Host Name

Type the name of the host in the provided box and click OK to open a session to that host, or choose a host from the Hosts: list by double-clicking its name.  This list is made up of two kinds of hosts:

>	Hosts in your hosts file

This is a file that you can create on your system to store host names.  You may or may not have a hosts file on your system.

>	Hosts in your hosts list

These are hosts that you connected to when Remember new hosts  is selected.  You can Edit Telnet Hosts for more information.


Telnet Custom Session Name

SPRY Telnet allows you to create custom sessions, telnet sessions which you create that save your current connection information (host name, port) and any settings for that connection (login script, colors, size, terminal settings, etc.).  This allows you to quickly connect to a host using the settings you prefer.  For more information on creating custom sessions, click Custom Telnet Sessions.


Telnet IP Address

You can also connect to a host by specifying its IP address (such as 165.121.100.1) or its Fully Qualified Domain Name (FQDN) (such as odysseus.circe.com).  Type the IP Address or FQDN in the supplied field, and click OK.


Telnet Port

SPRY Telnet is set to use a Telnet port of 23, which will work for most hosts.  Only change this number if you are connecting to a host whose port number is not 23.


Remember New Hosts

Checking this option in the <Open Telnet Session> dialog will cause SPRY Telnet to remember all the new hosts you type into the Host or Session Name or IP Address box, storing them in the Hosts list.  This option is checked "on" by default.  Uncheck this option if you don't want SPRY Telnet to remember the host you are connecting to and add it to your Hosts: list.

You can edit or delete hosts that you remember this way using the Edit Telnet Hosts dialog.


Opening Other Telnet Sessions

You can also start a Telnet session from within your current Telnet session by clicking the Open button on the Toolbar or choosing Open Session from the File menu.  You will see the <Open Telnet Session> dialog and can begin a new Telnet session.

You can easily switch between open Telnet sessions by using the Windows Task Switcher (holding down Alt and clicking the TAB key until you see the session you want, then letting go of both keys.)  Alternately, you can minimize sessions at the bottom of your screen using the Minimize arrow in the upper right hand corner of your Telnet Console or the Minimize option in the Telnet Windows System menu.


Edit Telnet Hosts

You can edit the name, address and port, and descriptions of each hosts you have connected to.  The <Edit Hosts> dialog displays all the hosts that you have "remembered" using the Remember New Hosts feature.

Note:	Hosts from your hosts file (as opposed to the hosts list stored by SPRY Telnet ) will not display in the Edit Hosts dialog.  They must be edited in the hosts file directly using a text editor.

Adding or editing a host

To add a host, click the New button, or click Edit to edit an existing host.  A dialog appears; the dialog will be empty if you are adding a host.

To add a host, fill in the host name, host address (either IP address or fully qualified domain name), and a description for the host (optional), and click OK.  The host will be added to your hosts list.

To edit a host, change the appropriate fields, and click OK.  You will see the changes you made the next time you start Telnet.

Deleting Hosts

To delete a host, select that host with your mouse by clicking on it to highlight the hosts name, then click Delete.  The host will be removed from the host list and will not appear the next time you start Telnet.


Telnet Menu Commands

File menu

Edit menu

View menu

Settings menu


File menu

Open Session

Open a Telnet session in a new window.

Save As Custom Session

Save current Telnet connection and settings to a custom session

Delete Custom Sessions

Delete custom Telnet sessions from Telnet

Capture Screen

Copy the currently displayed screen to a file.

Execute Script

Begin executing a Telnet script.

Echo To Printer

Send all subsequent Telnet screen output to a printer.

Capture To File

Send all subsequent Telnet screen output to a file.

Print

Print the selected text, or all available Telnet session text if no text is selected.

Print Setup

Change printer or printer options.

Edit Hosts

Edit hosts remembered using Remember New Hosts

Exit

Exit current Telnet session.


Edit menu

Copy

Copy currently selected (highlighted) text to the Windows Clipboard.

Paste

Paste contents of the Windows Clipboard to the current cursor position.

Select All

Select all available Telnet text.


View menu

Toolbar

Status Bar

The Toolbar at the top of the console contains buttons that serve as shortcuts for some of these menu items.  The Toolbar style can be changed by choosing Toolbar Style  from the Settings menu.

The Status Bar at the bottom of the screen displays concise help for SPRY Telnet menu items and contains display lights that show the status of Capture to File, Echo to Printer, and Num Lock.

Both the Toolbar and the Status Bar can be shown or hidden by checking or unchecking Status Bar or Toolbar in the View menu.  The Toolbar and Status Bar will be displayed if checked.


Settings menu

Session

Set up login script, capture file, and examine current session attributes.

Terminal

Set up Telnet terminal settings.

Colors

Set colors for the Telnet screen.

Font

Set the font used in the Telnet screen.

Toolbar Style

Set the style for the Telnet Toolbar.

Save Settings on Exit

Save all Telnet settings when exiting.


Save Settings on Exit

Check this option to use the current settings the next time this Telnet session is opened.


Printing in Telnet

Select text using the mouse, or select all the available session text by choosing Select All from the Telnet Edit menu.

Click the Print button on the Toolbar or

Choose Print from the Telnet File menu.

The Print dialog will appear; fill it out and click OK.  SPRY Telnet will print the selected text to the default printer (selected in Windows).  To print to a different printer, change Print Setup in the Telnet File menu before printing.

You can also choose to have all Telnet activity print to a printer; see Capturing text to a printer.


Print

The Print dialog will print any text you have selected, using the mouse or the Select All command.

SPRY Telnet will print the selected text to the default printer (selected in the Windows Control Panel).  To print to a different printer, click Setup, and specify a different printer.

You can also specify how many copies of your text to print, and what resolution of the printer should be used while printing.  Clicking Print to File will print to a file.


Print Setup

This dialog works like the <Print Setup> dialog in other Windows applications, allowing you to change the printer that is used, or set options for your existing printer.


Copying and pasting text in Telnet

You can copy some or all of the text on your Telnet screen to a printer or to the Windows clipboard.  Text copied to the Windows Clipboard can then be pasted into a different Windows application or can be pasted back into the Telnet screen at the cursor position.

Copying text from Telnet to the Windows Clipboard

Pasting text into Telnet


Copying text from Telnet

To copy text from Telnet, first highlight the text on the screen using your mouse.

To copy text to the Windows Clipboard:

Click the Copy button on the Toolbar or

Choose Copy from the Telnet Edit menu or

Click the right mouse button (with the text selected).

You will not notice any changes on your screen, but the selected text has been copied to the Windows Clipboard, and is now available to be pasted either in another Windows application (using that application's Paste command) or using the Paste command in SPRY Telnet.

________

See Also

Pasting text into Telnet


Pasting text into Telnet

The Paste command in SPRY Telnet will paste any information in the Windows Clipboard at the current cursor position.

Paste will only be available if you have recently used the Copy command in SPRY Telnet or in another Windows application, or if there is information currently in the Windows Clipboard from another source.

Note:	If there is no text data in the Windows Clipboard,  the Paste button and menu item will be disabled.

Also note that Paste will only work  if you are in a position where you can paste text; for instance, in a text editor with the cursor in insert mode.

To paste text into Telnet:

1)	First copy the text from the Telnet screen or from your Windows application (Copy or Cut will work in your Windows application).

2)	When you get to the place in your Telnet session where you want to paste information (at your prompt, in your editor, etc.):

Click the Paste button or

Choose Paste from the Telnet Edit menu or

Click the right mouse button.

The information you want to copy will be pasted (inserted) at the current cursor location.


Capturing text in a Telnet session

You can capture text from your Telnet session to a file or printer; this redirects all the output from your session to the file or printer from the moment you start the capture command.  SPRY Telnet also allows you to capture the currently displayed screen, copying it to a file.

Click on the appropriate capture topic for more information.

____

See

Capturing text to a file

Capturing text to a printer

Capturing the screen


Capturing text to a file

Click on the Capture to File button or

Choose Capture to File in the Telnet File menu.

Click Setting up a Capture File for information on how Capture Files are setup and used.

When you start Capture to File, the Capture light on the Status Bar will turn on, reminding you that everything generated during your session is being saved to a file.

To end capturing to a file, click again on the Capture to File button, or select Capture to File from the File menu (unchecking the menu option).  The Capture light will turn off, and the Capture File will be closed.

Note:	If you want to automatically capture your sessions to a file when you start Telnet, exit Telnet with the Capture command active, and Save Settings on Exit chosen.  Your current capture file will be closed, and the next time you start the same Telnet session, capture will start automatically.


Setting up a Capture File

If you have not specified a filename to automatically capture the session to, Telnet will assign one, named CAPTUR##.TXT or CAPTUR##.DAT, where ## is a number from 00 to 99, and automatically capture to that file.  This number is incremented each time you do a capture.  (When the CAPTUR99 file is reached, it will restart again with CAPTUR00).

Alternately, you can specify a filename to capture your sessions to by specifying a Capture File in the Session dialog in the Telnet Settings menu.  Click the Browse key with your cursor in the Capture File field to search your directories for an existing login script.  If you have a filename selected, you will be asked each time you capture whether you want to write over that file.

There are two ways you can capture text to a file.  You can capture Text Only, or you can capture Text and Control Characters.  Text Only is the default; Text and Control Characters will capture everything that comes from the host, such as control codes, escape codes, line feeds and carriage returns.   This is also set in the Session dialog.


Capturing text to a printer

Click on the Echo to Printer button on the Toolbar or

Choose Echo to Printer in the Telnet File menu.

All subsequent session text will be printed on the default printer (selected in Windows).  To print to a different printer, change Print Setup in the Telnet File menu before printing.

The Print Echo light on the Status Bar will be turned on and will remain on until you have finished capturing text to the printer.

To end capturing text to the printer, click again on the button, or select Echo to Printer from the File menu (unchecking the menu option).  The Print Echo light will turn off, and text will stop printing.

Note:	If you want to automatically capture your sessions to a printer when you start Telnet, exit Telnet with the Echo to Printer command active, and Save Settings on Exit chosen.  The next time you start the same Telnet session, print capture will start automatically.


Capturing the screen to a file

Click on the Capture Screen button or

Choose Capture Screen from the Telnet File menu.

You will be prompted for a filename to capture the file to.  Click Capture Screen  for more information.


Capture Screen

The <Capture Screen> dialog prompts you for a filename for this screen capture.  The default extension for this file is .cap.

Type the filename for the screen capture.  If you choose a name that does not exist, it will be created.  Click OK.

The screen will be saved to the named file, the file will be closed, and you will return to the Telnet Console.

The currently displayed screen will be captured to an ASCII file with each line terminated by a <CR><LF> pair.  This makes it easy to load the image into a word processor or text editor for inclusion in a document.

Note:	If the screen you are capturing contains DEC Special Graphics characters, they will be translated to their nearest ASCII equivalents before being written to disk.


Using Scripts in Telnet

SPRY Telnet includes a basic script language which allows you to create scripts that you can execute to automate repetitive tasks, like logging in or typing a frequently used sequence of commands.  You can create a script file for SPRY Telnet using an ASCII text editor like Windows Notepad.  SPRY Telnet includes a basic script language which allows you to create scripts that you can execute to automate repetitive tasks, like logging in or typing a frequently used sequence of commands.  You can create a script file from within SPRY Telnet, or use an ASCII text editor like Windows Notepad to create a script at any time.

The script language and a sample script follow, along with instructions on how to run a Telnet script.

Note:	SPRY Telnet looks for script files with the extension .scp by default, so you may want to name your script files with this extension.

____

See

Setting up a Login Script

Telnet Script Commands

Executing a Telnet Script


Setting up a Login Script

You can set up a login script to run every time you start a particular Telnet session, as described below.

1)	Choose Session in the Telnet Settings menu or click the Session button on the Toolbar.

2)	Click your mouse in the Login Script field so that your cursor displays in that field.

If you have not yet created a Telnet Login script, choose a name for the Telnet script, and click Edit.  (The name must be in standard DOS filename format; an extension of .scp is suggested).  This will bring up a Windows Notepad session.  Create your login script by typing the commands for the script in Windows Notepad, then choose Save from the Windows Notepad menu.  You will return to the Session dialog.

or

If you have already created a login script, specify that filename in the Login Script field, or click Browse to locate the login script.

3)	Click OK.  This login script you created or specified will now be identified with the current Telnet session and will execute the next time you start this session.  Note that you must have Save Settings on Exit in the Settings menu checked to save this change.

Note:	If you want to alternate several different scripts, you will probably want to set up different custom sessions in Telnet that each use different login scripts.  Click Custom Telnet Sessions for more information.


Telnet Script Commands

The SPRY Telnet script language consists of the statements below.  A sample Telnet script is also shown.

wait <secs> "<string>"

This statement causes SPRY Telnet to scan the incoming data stream for an occurrence of the text string specified by "<string>" (Note: the angle brackets indicate a user-supplied value; they are not part of the 'wait' statement itself. The quotation marks, on the other hand, are mandatory). The <secs> parameter (optional) indicates the number of seconds that SPRY Telnet should wait for the specified string before giving up. If the string is not detected within the specified number of seconds, the script will abort.

type "<string>"

This statement causes SPRY Telnet to transmit the specified text string to the host, as though it had been typed by the user at the keyboard. As with the 'wait' statement, the quotation marks are mandatory.  You can include control characters in the <string> by including a caret followed by the control character.  For example, ^M represents a carriage return, so type "ls^M" would type the characters ls followed by a carriage return.

You can also include non-printing characters in the string using C-style octal digits, preceded by a backslash (e.g., '\033' for the 'escape' character).

goto <label>

This statement will jump to the name of a line in the script you've created.  A label in a script is a word on one line begining with a colon.

if_err_goto <label> and if_noerr_goto <label>

These statements usually follow the wait statement in a script.  If the wait statement does not receive the string it is waiting for in the time allotted, an error will be generated, and any if_err_goto statements that follow will be executed, moving the script execution to the area of the script specified by the label.  For instance, you could jump to :nopromptfound, and type "String not received!".  If no error is received, if_noerr_goto statement will be executed.

end

If this statement is encountered in a script, the script will end.

You can also include comments in a Telnet script by starting the line with a forward slash / character.

Sample Telnet Script

Here is a sample login script for John Doe:

/This a login script for John Doe

/to log him into his Sun workstation

wait 3 "LOGIN:"

if_err_goto nologin

type "johndoe^M"

wait 1 "PASSWORD:"

type "cucumber"

:nologin

end


Execute Script

Execute Script will run any Telnet Script you specify.  Specify your Telnet script in this dialog; Telnet will look for files with the extension .scp by default.

Click Telnet Script Commands for a description of the commands in the Telnet script language.

Click Setting up a Login Script to learn how to set up a script to run every time you start a particular Telnet session.


Customizing Telnet Settings

You can customize SPRY Telnet using the Telnet Settings menu.

Note that changes to these settings options will take effect for the current session only if Save Settings on Exit is not checked.


Session Setup

The Session dialog box identifies which host and port you are connected to during your current Telnet session, and allows you to add an optional description of the current host or custom session and change the Login Script and Default Capture Filename for the session.

Click the option for which you want help.

Description

Login Script

Capture File

Capture Mode


Description

This allows you to provide a description for your Telnet sessions and custom sessions that will display in the <Open Telnet Session> dialog box.


Login Script

You can have a login script run automatically when you start SPRY Telnet by specifying a filename in this field.  Click the Browse key with your cursor in the Login Script field to search your directories for an existing login script or click the Edit key to create or edit your SPRY Telnet Login Script.

Click Setting up a Login Script for more information.


Capture Mode

When you capture session text to a file, you can capture as Text Only (standard) or as Text and Control Characters (text and non-displaying control characters such as line feeds, carriage returns, escape codes, bold and underline codes).  Click whichever mode you prefer.

See Capturing text to a file for more information


Terminal Setup

The Terminal dialog lets you set Telnet terminal options, such as terminal emulation and size.  Click the option below that you want help with.

Emulation

Size

Modes

Control Codes

Cursor Keys

Keypad

Backspace

You can also map your Telnet keyboard from this screen by clicking Keyboard.  Click Remapping Keys in Telnet for more information on mapping your keyboard.


Emulation

VT52, VT102, or VT220

You can set terminal emulation for VT52, VT102, or VT220.  Remember that this option is set only for this session if you do not have Save Settings on Exit checked.


Size

80 or 132 column mode

SPRY Telnet can be set to either 80 or 132 column mode.  The screen width will change to reflect the column mode chosen (in conjunction with the current font selected).

Note:	You may not be able to see all 132 columns on your screen at the same time unless you have a small font chosen.  The suggested fonts to use are Telnet VT Narrow (Super VGA screens) or Telnet VT Extra Narrow (VGA Screens).

24 Lines

Some UNIX applications only operate properly in a 24-line screen.  If this option is checked, your screen will be restricted to a maximum of 24 lines regardless of how you change your font or window size.


Modes

Auto Wrap

If this option is checked, lines of text you type off the edge of your current screen will wrap around to the next line.  If this option is unchecked, text you type off the edge of your screen is still accepted, but will not wrap to the next line on the screen (and will not be visible).

Local Echo

If the connection type of the host you're connecting to is "half duplex", then characters you type are not automatically sent back to the screen.  If this is the case, you will want to set the local echo option on.  The default setting is off; most hosts are "full duplex" and will automatically echo to your screen.

Bell

Applications or commands that you run on your host may produce a Bell  control code, causing your terminal to beep.  Uncheck the Bell option if you do not want to hear the Bell.

CR=CR+LF

Some hosts may want you to send a carriage return and a line feed whenever you press a Carriage Return (the Enter key).  The default is to send only a Carriage Return.

Scroll Back

You can enable or disable the Telnet scroll back buffer by checking/unchecking Scroll Back.  If the scroll back buffer is enabled (the default), the Telnet scroll bar will appear along the right hand side of the screen, and you will be able to scroll up and down the Telnet screen.  Unchecking this option will remove the Telnet scroll bar.

You can specify the number of lines you want  your Telnet screen to scroll back; the default number of lines is 48 (approximately two Telnet screens).  You can increase or decrease this number to any value from 0 to 255 (0 means no scrollback, and 255 is the maximum, approximately ten Telnet screens).  Note that every 48 lines of scroll back buffer uses up approximately 40K of Windows system memory.

Setting the Scroll Back buffer number will only have an effect if you have Scroll Back checked.


Control Codes

For debugging purposes (or sheer curiosity) you may want the control codes sent from the host to appear on your screen.  This would include control codes that represent bold and underline, line feeds, bell commands, etc.  If you check Display, these commands will display on your screen (in a form similar to '^X').  Necessary control characters (like line feed and carriage return) will still execute, but choosing Display will cause many of these control characters to display only.  Interpret is the default setting for this option.


Cursor Keys

The cursor keys on your keyboard (arrow keys, usually in a T-shape, distinct from the number keypad) may be set to send out control codes for your application, rather than the standard ANSI codes.  Choose Application to set the cursor keys this way; the default setting is Normal.


Keypad

Like the cursor keys, the numeric keypad can be set to send out application control codes, rather than their standard numeric values.  The default setting is Numeric.


Backspace

This allows you to select whether the Delete key or the Backspace key on your keyboard will issue the Backspace command in your applications.


Color

You can set colors for your Telnet background, text, and bold text.

Choose Terminal Text, Terminal Background, or Terminal Bold Text from the Screen Element menu, and choose a color from the displayed color palette.  The colors will change on the Sample screen, and you can click OK to save them.  They will take effect only in the current session unless you have Save Settings on Exit checked.


Font

You can change the font, font style and size that Telnet uses to display text.  Changing the fonts in Telnet will change the text appearance on the screen, and the screen window will resize to maintain the current view.

The Font dialog box displays a standard Windows font selection screen.  Choose the font, font style and font size you want for the current session and click OK.  The font changes will take effect only in the current session unless you have Save Settings on Exit checked.


Toolbar Style

This setting allows you to change the appearance of the Toolbar shortcut buttons.  You can choose between three different displays:  Both Picture and Text, Picture only, or Text only.  Click the appropriate radio button to select the Toolbar style, and click OK.


Custom Telnet Sessions

Although you can save SPRY Telnet settings at any time by changing them with the Telnet menus and exiting with Save Settings on Exit, your changes will affect all Telnet sessions.  If you want to set up different settings for different Telnet hosts, you will want to create custom sessions.

Custom sessions are especially useful for setting up login scripts that can automatically log you into your host and start a host application.  You can also set up different colors, fonts, terminal settings for each custom session.  Basically, any option you can set in the Telnet menus can be set during a custom session, and those changes will affect only that session.

Once you have created a custom Telnet session, you can update the session settings at any time.

____

See

Creating a Custom Session

Starting a Custom Session

Updating a Custom Session

Deleting a Custom Session


Creating a Custom Session

1)	Connect to the host for which you want to create a custom session.

2)	Set your Telnet options the way that you would like them for the custom session, including a custom login script, if desired.

3)	Choose Save As Custom Session from the File menu.  You will be prompted for the name of a session. Type a new name to create the new session.

Note:	After creating a custom Telnet session, you should exit and restart Telnet before creating another Telnet session.

____

See

Starting a Custom Session


Save Settings As Custom Session

The Save Settings As Custom Session dialog allows you to save the current Telnet connection and associated settings to a custom session.

Session Name:	Specify a name for the custom session (names of any length are acceptable, but they may not contain spaces).

Description:	Specify an optional description for the custom session; this will show up in the <Open Telnet Session> dialog when you highlight the session name.

When you click OK, the custom session will be created.  The session will display in your Open Telnet Session dialog the next time you start SPRY Telnet.


Starting a Custom Session

You can start custom Telnet sessions from the Open Telnet screen.  Type the session name in the Host, IP address or Session Name box, or choose the Custom Session name from the drop down Session: list box, and click OK.

The Telnet Console will open with the custom Session you created.

________

See Also

Updating a Custom Session

Deleting a Custom Session


Updating a Custom Session

If you make changes and have Save Settings on Exit checked, the settings in the session you are using will be updated when you exit SPRY Telnet.

Alternately, you can choose Save As Custom Session from the File menu.  You will be prompted for the name of a session.  Type an existing session name; the current session will be updated (overwritten) with the current settings, and your session name will change to the name you specified.

You can change the session description that appears in the Open Telnet Session dialog by choosing Session in the Settings menu and changing the Description field.

________

See Also

Deleting a Custom Session


Delete Custom Sessions

The Delete Custom Sessions command allows you to specify custom sessions to delete.

Choose the custom session you want to delete, from the drop down list (the associated host and port information will appear when you choose the session name, so that you know which custom session you are deleting.)  Choose Delete to delete the session displayed in the drop down list, or Cancel to exit without deleting any sessions.


Remapping Keys in Telnet

SPRY Telnet automatically maps all DEC VT keyboard keys to standard keys on your IBM enhanced keyboard, so that your Telnet session will perform like a terminal.  When you press a key on your keyboard, it will emulate a certain DEC VT key automatically. (These mappings only take effect while you are using Telnet; your other Windows applications are not affected).

SPRY Telnet's Keyboard Mapping utility allows you to change these mappings, and create new ones.  You can remap different DEC VT keys, terminal functions, text, or control characters to your PC keys.

For example, an application might expect you to press the DEC VT Find key, which doesn't exist on a standard 101-enhanced keyboard.   SPRY Telnet automatically maps this key to the Insert key on your PC keyboard; when you press Insert in a Telnet session, it is equivalent to VT Find.  If you prefer, you could map another key to DEC VT Find.  On a VT keyboard, the first five function keys (F1-F5) have specific terminal functions assigned to them (F5 is VT Function SendBreak, for instance).  These functions, as well as a few additional unassigned functions (such as VT Function ToggleNumKeypadMode) can be mapped to any key on your keyboard.

Also, in an SPRY Telnet session, you might frequently type the "ls -Rlag" command to list files.  You could use Keyboard Mapping to map this a key or key combination (i.e. F12), so that you do not have to type that command out each time you want to list files, but could simply type one key on your keyboard.

____

See

Starting Keyboard Mapping

Using Keyboard Mapping


Starting Keyboard Mapping

1)	In SPRY Telnet, choose Terminal from the Settings menu

or

Click the Terminal button on the SPRY Telnet Toolbar.

2)	Click the Keyboard button.  You will see the <Keyboard Mapping> dialog, allowing you to remap the keys on your keyboard.

You can now list the standard keymappings for Telnet, or map any of your Telnet keys.

____

See

Using Keyboard Mapping


Keyboard Mapping

The <Keyboard Mapping> dialog lets you list existing keyboard mappings in Telnet, and select and map keys.

Click Viewing the Current Keymappings for information about viewing all the mappings in Telnet.

Selecting a Key to Map:

All of the keys that display on the <Keyboard Mapping> dialog can be mapped, with the exceptions of Caps Lock, Shift, Ctrl, and Alt.

Click the key you want to remap with your mouse.  The name of the key you have clicked will display next to PC Key.  The DEC VT key or function that this PC key currently emulates will be displayed in the Maps to: field.

To map a [Shift] or [Ctrl] key combination, click the [Shift] or [Ctrl] key, and then click the key you want to map along with it.

There are two ways you can remap a key in SPRY Telnet:

>	Map a key to a key or VT terminal function, by choosing from the drop down list.

>	Map a key to text or control characters by typing directly in the Maps to: field.

____

See

Mapping a Key using the Drop-Down List

Mapping a Key by Typing


Viewing the Current Keymappings

You can use the List button in the <Keyboard Mapping> dialog to display the current keymappings in use by Telnet.  Initially, this will be the default keymappings that are provided with Telnet; any changes you make to the keymappings will also be reflected in this list.

The keymapping list is indexed by VT key to make it easy to find out which PC key you need to press to transmit that VT key.

Note:	The default key mappings are by location; if you are familiar with a DEC VT keyboard, the keys will be in the same approximate place on your PC keyboard as on the DEC VT keyboard.


Mapping a Key using the Drop-Down List

SPRY Telnet automatically maps DEC VT keys to certain keys and key combinations on your PC keyboard.  These key values, and a few others, are listed in the drop down list in the <Keyboard Mapping> dialog.  You can select any key, and map it to one of those drop down keys, by choosing the key value from the drop down list.

You might frequently use the Shift-TAB combination in one of the applications you use during a Telnet session.  You could map this key combination to F12 or another key you do not use, so that you can easily execute Shift-TAB.

To cancel the mapping you've made on any key, choose that key and click Set to Default.  To cancel all the changes you've made and return to the default keymappings, click Reset to Default.

You can continue to map keys by choosing new keys on the PC keyboard.  If you click OK to exit this dialog, all the changes you've made will be saved, to take effect in the current session.

You can also save keyboard mappings so that they can be used in other sessions; see Saving and Loading Keymappings.


Mapping a Key by Typing

You can remap a key to text or control characters (or combination of the two) by choosing the PC key you want to map, and then typing the characters you would like to map to that key in the Maps to: field.

Anything you type into the field directly is treated as text that should be typed directly in Telnet when the mapped key is pressed.  Control characters can be typed in three ways:

>	Control Character Notation	i.e. ^G, ^M, ^[

^ followed by the character to be modified.

>	Mnemonic Notation	i.e. [BEL], [CR], [ESC]

[ ] enclosing the control character Mnemonic

>	Octal Notation	i.e. \007, \013, \033

\ followed by the three character octal value

The syntax shown above must be followed exactly. Click Control Code Notations for a list of the most commonly used control characters.

For instance, you might want to map F11 on your PC keyboard to the word exit, followed by a carriage return (the Enter key), so that you could easily exit your Telnet session by pressing F11..

You would do this by clicking F11 to map the key, and then typing exit^M in theMaps to: field ( ^M represents a carriage return).  Alternately, you could type exit[CR] or exit\015.  (No spaces should be used, unless you want spaces to be typed on the screen).

To cancel the mapping you've made on any key, choose that key and click Set to Default.  To cancel all the changes you've made and return to the default keymappings, click Reset to Default.

You can continue to map keys by choosing new keys on the PC keyboard.  If you click OK to exit this dialog, all the changes you've made will be saved, to take effect in the current session.  Keyboard mappings can be saved for use in other sessions; see Saving and Loading Keymappings.


Control Code Notations

A list of commonly used control codes with notations is shown below.

Common Control Code Notations

Control	Mnemonic	Octal	Character	Notation	Notation	Notation

Escape	^[	[ESC]	\033

Delete	[DEL]	\177

Null	^@	[NUL]	\000

Ctrl-A	^A	[SOH]	\001

Ctrl-B	^B	[STX]	\002

Ctrl-C	^C	[ETX]	\003

Ctrl-D	^D	[EOT]	\004

Ctrl-E	^E	[ENQ]	\005

Ctrl-F	^F	[ACK]	\006

Ctrl-G (Bell)	^G	[BEL]	\007

Ctrl-H (Backspace)	^H	[BS]	\010

Ctrl-I	^I	[HT]	\011

Ctrl-J (Line Feed)	^J	[LF]	\012

Ctrl-K	^K	[VT]	\013

Ctrl-L (Form Feed)	^L	[FF]	\014

Ctrl-M (Carriage Return)  ^M	[CR]	\015

Ctrl-N	^N	[SO]	\016

Ctrl-O	^O	[SI]	\017

Ctrl-P	^P	[DLE]	\020

Ctrl-Q	^Q	[DC1]	\021

Ctrl-R	^R	[DC2]	\022

Ctrl-S	^S	[DC3]	\023

Ctrl-T	^T	[DC4]	\024

Ctrl-U	^U	[NAK]	\025

Ctrl-V	^V	[SYN]	\026

Ctrl-W	^W	[ETB]	\027

Ctrl-X	^X	[CAN]	\030

Ctrl-Y	^Y	[EM]	\031

Ctrl-Z	^Z	[SUB]	\032


Saving and Loading Keyboard Mappings

Keyboard mappings you make are saved in the current session only (if you are running a custom session, they will be used whenever you invoke this custom session).  If you want to save your keyboard mappings so that they can be used in other Telnet custom sessions, you can use the Save command; you can use the Load command to load in other keyboard mappings.

____

See

Saving Keymappings

Loading Keymappings


Save Keymap As

After mapping all the keys you want to save, clicking the Save button in the <Keyboard Mapping> dialog will produce the Save Keymap As dialog, prompting you to name and save the current keyboard mappings.

Fill out this dialog with information about the keyboard mappings; this information will be displayed when you load in a keyboard mapping.  Name is the only required field, although you can also give this keymapping a short name (to be used as the file name) and a description.

Click OK; the keyboard mapping set will be saved.  You can then load the keyboard mappings in another session.

____

See

Loading Keymappings


Load Keymap

In the Telnet session where you want to load in a set of saved keyboard mappings, you can click the Load button in the <Keyboard Mapping> dialog to produce the <Load Keymap> dialog.  This screen will display all the keyboard mappings you have previously saved using the Save button.

Choose the mappings set you want to load in, and click OK.  The keymappings will now be used in the current session (if your current Telnet session is a custom session, they will now be used every time you use this custom session).


Exiting Telnet

Logging out of your remote host will automatically exit SPRY Telnet; this is the recommended way to exit a Telnet session.  You can also exit an SPRY Telnet session by choosing Exit from the File menu or by doubleclicking the Windows System menu in the upper left hand corner of the Telnet console.  This will only close the Telnet session that is currently active.  You must individually close each session you have open; there is no way to close all open Telnet Sessions.


Telnet Dynamic Data Exchange (DDE)

Dynamic Data Exchange, commonly referred to as DDE, is used for interprocess communications. It allows programs such as Excel, Word for Windows, and Visual Basic to interface SPRY Telnet.  With the DDE interface, you can create new terminal sessions, enter data, retrieve screens, and run macros and scripts.  For example, with the DDE interface, you can write macros in Word for Windows to log you into a host and then send mail automatically.

This help topic describes Telnet's DDE implementation in some detail.  It is recommended that you print this help topic if you need to refer to it.

How DDE Works

DDE transfer information in conversations. A conversation is carried out between a client application and a server application. A server application can be an application like SPRY TN3270 and SPRY Telnet.

When SPRY Telnet is loaded, it broadcasts to DDE that its services are available. Then a client application such as Word for Windows can initiate a conversation with SPRY Telnet. You can compare a conversation to a telephone call. You must call your friend in order to have a conversation. Once a conversation is established, the client application can request information, press keys and run scripts.

There are four main types of DDE messages that can be issued from a client application: a Request message, a Poke message, an Execute message, and an Advise message.

The Request message is used to get information back from the server application. For example, you might request a copy of the screen, known as the Presentation Space. You would use a Poke message to press keys, move the cursor, or copy a block of data directly into the presentation space. Execute messages are used to execute session or system commands. You use execute messages to run scripts or macros, and open new terminal sessions. Last, the Advise message is used to create warm or hot links with the emulator. This message is used to have the host inform your client application when certain events occur.

There are two necessary fields used in all DDE conversations: the application name and the topic.

The application name directs the DDE conversation to a particular application. The application name for SPRY Telnet is AIRTEL.

The topic specifies the terminal session identifier.  For SPRY Telnet this is a number (1 for the first session, 2 for the second, etc). There is a special topic called SYSTEM which allows you to perform non-session oriented functions.

A third and often used field is the item. The item usually specifies the request or command issued to the session or system.

Terminology

The following terms and values are important for most aspects in using the DDE interface.

The screen is commonly referred to as the Presentation Space or PS. When copying information to/from the PS, the indexes used always begin at 1 and end at the last value of the PS. For example, a 24x80 screen as 1920 addressable positions which range from 1 to 1920.

Some of the requests return multiple items back to you in a single string. Each item is delimited using the carriage return byte,(\r in standard C syntax) value 0x0D or 13 decimal.

Starting a Conversation

To start a conversation with SPRY Telnet, you must send an INITIATE message with AIRTEL as the application name and a topic which can be the session identifiers (such as 1) or SYSTEM.

Word for Windows

To start a conversation in Word for Windows WordBasic, use the following syntax in a macro:

iChanNum = DDEInitiate ( AIRTEL, 1 )

The topic 1 can be replaced with any other existing session identifier or SYSTEM to access the system topic.

Microsoft Excel

To start a conversation in Microsoft Excel, use the following syntax in a cell:

=INITIATE( AIRTEL, 1 )

System Topic

The System topic is very useful to find out information about the system. For example, it allows you to see what sessions are currently in use. The System topic supports the following items which can be requested using the Request command:

Command	Description

Formats	Returns the list of supported DDE data formats. Currently, only the Text format is supported.

Help	Returns application identification information.

Sessions 	Returns the list of custom saved sessions in Telnet.

Start Session 	Starts a session.

SysItems	Returns a list of available items that can by queried for the System Topic. Each item is delimited using a carriage return \r.

Topics	Returns a list of available topics that can be used in conversations. The list always includes the System topic and the session short names of connected sessions. Each item is delimited using a carriage return \r.

Getting Information using the Request Message

The Request message is used to get information back from the DDE server, SPRY Telnet. It allows you to retrieve information such as the screen format, cursor position, and the presentation space. Requests are only used to get information back. They do not perform any actions on the emulator or system.

REQUEST Item Names

The following is a list of available items that can be requested from a session topic.

Item Name	Description

Columns	returns the number of columns in the current presentation space.

Cursor	returns the current cursor location in the presentation space. 1 is the first position.

Custom Session Name 	Returns the name of the custom session used for the PS, or TELNET if none.

Emulation 	Returns the VT model for the PS.

Rows	returns the number of rows in the current presentation space.

Search	returns the position of the search string in the presentation space. The search string is defined using the POKE command.

PS	returns the entire contents of the presentation space. The entire space is returned as one string. Nulls are converted to blanks. Therefore, if you have a Model 2 terminal (24x80), a string of 1920 bytes will be returned.

Window Handle 	Returns the window handle of the window displaying the PS.

Pnnnn[Lmmmm] 	Returns a portion of the PS starting at location nnnn and extending to the end of the PS, or optionally for length mmmm. 1 is the upper-left corner.

Rnnn	returns the contents of the specified row. Nulls are converted to blanks.

The following item names can be requested from the SYSTEM topic.

Item Name	Description

Formats	returns the name of the DDE formats supported. Always returns Text.

Help	Returns application identification information.

Sessions 	Returns the list of custom saved sessions in Telnet.

SysItems	returns the list of system items that can be requested. Each item is separated by a carriage return character (0x0D).

Topics	returns the list of system topics that are currently available for conversations. Each item is separated by a carriage return character (0x0D).

Sending Information using the Poke Message

The Poke message is used to send information to the DDE server. It allows you to send information such as the screen data, new cursor position, press keys, and set the search string. Poke does not return any information.

POKE Item Names

The following is a list of available items that can be sent to a session topic.

Item Name	Description

Keystroke 	Sends the collection of keypresses in <string> as if they had been entered from the keyboard. <string> can contain ASCII control codes in the ^A literal format and can contain OCTAL codes in the /000 format.

Run Script 	Runs the script whose filename is in <filename>.

Wait For 	Sets the wait string to <string>.

The following item can be sent to the SYSTEM topic.

Item Name	Description

Start Session	Starts a session as specified in <string>:

<custom session name> | <host name> | <IP address>[, <IP port>]

Running commands using the Execute Message

The Execute message is used to instruct SPRY Telnet to perform the End Session command. Execute does not return any information.

EXECUTE Item Names

The following item can be issued to a session topic.

Item Name	Description

End Session	Terminates the current terminal session. This is identical to selecting Exit from the File menu in SPRY Telnet

Monitoring Session Activity using the ADVISE Message

You can use the ADVISE message to receive feedback of when certain events take place such as cursor movement or presentation space updates. These are known as warm or hot links in the DDE terminology. This allows your application to receive update information when a specified event takes place.

As mentioned, there are two types of advise links: warm links and hot links. A hot link updates your client information automatically whenever changes occur, whereas a warm link requires additional steps to update your client information. Hot links are usually used to provide continuous up-to-date information.

Examples

The following function will request advisement when the cursor changes position.

Word for Windows

1)	Insert a field in your document by pressing the INSERT FIELD key, Ctrl+F9.

2)	Enter the DDE command below for a warm or hot link. Do not enter the curly brackets. They are the field delimiter characters.

{ dde application name session name item name }

{ ddeauto application name session name item name }

Example:

{dde airtel 1 Wait For }

ADVISE Item Names

The following is the description of the ADVISE Item for SPRY Telnet.

Item Name	Description

Wait For 	Advises caller when the wait string is first encountered in the PS.

Example of DDE Calls

The following is an example of DDE call in SPRY Telnet.

Sub MAIN

Run SPRY Telnet and login before running this Word 6.0 Basic macro

ChanNum = DDEInitiate (AIRTEL, 1)

DDEPoke ChanNum, Keystroke, finger rlord@spry.com^M

DDETerminate ChanNum

 Observe the command and its result in SPRY Telnet

End Sub